<?php
/**
 * Presentation of a table field for Advanced Module. Can be used to alter
 * displaying of the field in the list, formating of the value, format the
 * value, format form field or the way the field's filtering is presented.
 */
abstract class Presentation {
    /**
     * DBDriver for database access.
     *
     * @var DBDriver
     */
    protected $dbdriver;
    
    /**
     * Localization strings.
     *
     * @var array
     */
    protected $langArray;
    
    /**
     * Called during the initDisplay method of the module when form is about to
     * be displayed.
     */
    public function initFormDisplay() {}
    
    /**
     * Returns true if the field should not be displayed in the list.
     *
     * @return boolean True if the field should not be displayed in the list.
     */
    public function isHiddenInList() {
        return false;
    }
    
    /**
     * Fixes the input value so it can be stored in the database.
     *
     * @param mixed $current Current value set in the record modified by
     *        current input. Is null when not set.
     * @param mixed $rawInput Infiltered input value as provided by the user.
     *        Is null when not set.
     * @return mixed Fixed input value so it can be stored in the database.
     */
    public function fixInput($current, $rawInput) {
        return $current;
    }
    
    /**
     * Formats form field definition before it's displayed. May be used also to
     * format the field value.
     *
     * @param array $field Basic form field definition.
     */
    public function formatFormField(&$field) {
        $field['value'] = isset($field['value']) ?
                $this->formatForForm($field['value']) : '';
    }
    
    /**
     * Formats the field's value for form. By default the formatting is done by
     * the function formatForList.
     *
     * @see formatForList
     * @param mixed $value The unformatted raw value as retrieved from the
     *        database.
     * @return mixed Formatted value that will be used in the form.
     */
    public function formatForForm($value) {
        return $this->formatForList($value);
    }
    
    /**
     * Formats the field's value for list.
     *
     * @param mixed $value The unformatted raw value as retrieved from the
     *        database.
     * @return mixed Formatted value that will be used in the list.
     */
    public function formatForList($value) {
        return $value;
    }
    
    /**
     * Returns the type of input field for the filtering of the list.
     *
     * @return string Filtering field type.
     */
    public function getFilteringType() {
        return 'text';
    }
    
    /**
     * Sets the DB Driver instance. This method is invoked automatically by the
     * AdvModule API during module's initialization.
     *
     * @param DBDriver $dbdriver 
     */
    public function setDBDriver($dbdriver) {
        $this->dbdriver = $dbdriver;
    }
    
    /**
     * Sets the lang array containing localized strings. This method is invoked
     * automatically by the AdvModule API during module's initialization.
     *
     * @param array $langArray 
     */
    public function setLangArray(&$langArray) {
        $this->langArray = &$langArray;
    }
    
    /**
     * Returns localized string for the provided key.
     *
     * @param String $key
     * @return String The localized string.
     */
    protected function lang($key) {
        return isset($this->langArray[$key]) ? $this->langArray[$key] :
                "???$key???";
    }
}